/*
 * @(#)MeteDataProvider.java	1.0 2000/12/20
 *
 * Copyright 2000 Thomas Barnekow. All Rights Reserved.
 *
 * This software is the proprietary information of Thomas Barnekow.
 * Use is subject to license terms.
 */

package tb.provider;

import tb.util.*;

/**
 * This interface is to be implemented by meta-data {@link Provider}s.
 * Describing entities is a mandatory operation. Declaring them is optional.
 *
 * @author Thomas Barnekow
 * @version 1.0
 */
public interface MetaDataProvider extends Provider {

  /**
   * Compound service comprising {@link #DESCRIPTION} and {@link #DECLARATION}.
   */
  public static final QualifiedName META_DATA =
    new QualifiedName(SERVICE, "meta-data");

  /**
   * The meta-data description service.
   *
   * @see #describe
   */
  public static final QualifiedName DESCRIPTION =
    new QualifiedName(META_DATA, "description");

  /**
   * The default meta-data description service.
   *
   * @see #describe
   */
  public static final QualifiedName DEFAULT_DESCRIPTION =
    new QualifiedName(DESCRIPTION, "default");

  /**
   * The meta-data declaration service.
   *
   * @see #declare
   */
  public static final QualifiedName DECLARATION =
    new QualifiedName(META_DATA, "declaration");

  /**
   * Describe the given <code>entity</code>, which can be a container or an
   * element.
   *
   * @param entity  container or element
   * @return        entity description
   */
  public MetaObject describe(QualifiedName entity) throws Exception;

  /**
   * Declare the given <code>entity</code>, which can be a container or an
   * element. This is an optional operation.
   *
   * @param entity  container or element
   * @param mo the  meta-object producing a declaration, which must be understood
   *                by the actual service provider
   *
   * @exception UnsupportedOperationException if this operation is not supported
   */
  public void declare(QualifiedName entity, MetaObject mo) throws Exception;
}